 /*
  * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/ServiceFactory.java,v 1.10 2007/02/20 00:16:30 hargrave Exp $
  *
  * Copyright (c) OSGi Alliance (2000, 2007). All Rights Reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 package org.osgi.framework;

 /**
  * Allows services to provide customized service objects in the OSGi
  * environment.
  *
  * <p>
  * When registering a service, a <code>ServiceFactory</code> object can be
  * used instead of a service object, so that the bundle developer can gain
  * control of the specific service object granted to a bundle that is using the
  * service.
  *
  * <p>
  * When this happens, the
  * <code>BundleContext.getService(ServiceReference)</code> method calls the
  * <code>ServiceFactory.getService</code> method to create a service object
  * specifically for the requesting bundle. The service object returned by the
  * <code>ServiceFactory</code> is cached by the Framework until the bundle
  * releases its use of the service.
  *
  * <p>
  * When the bundle's use count for the service equals zero (including the bundle
  * stopping or the service being unregistered), the
  * <code>ServiceFactory.ungetService</code> method is called.
  *
  * <p>
  * <code>ServiceFactory</code> objects are only used by the Framework and are
  * not made available to other bundles in the OSGi environment. The Framework
  * may concurrently call a <code>ServiceFactory</code>.
  *
  * @see BundleContext#getService
  * @ThreadSafe
  * @version $Revision: 1.10 $
  */

 public interface ServiceFactory {
     /**
      * Creates a new service object.
      *
      * <p>
      * The Framework invokes this method the first time the specified
      * <code>bundle</code> requests a service object using the
      * <code>BundleContext.getService(ServiceReference)</code> method. The
      * service factory can then return a specific service object for each
      * bundle.
      *
      * <p>
      * The Framework caches the value returned (unless it is <code>null</code>),
      * and will return the same service object on any future call to
      * <code>BundleContext.getService</code> from the same bundle.
      *
      * <p>
      * The Framework will check if the returned service object is an instance of
      * all the classes named when the service was registered. If not, then
      * <code>null</code> is returned to the bundle.
      *
      * @param bundle The bundle using the service.
      * @param registration The <code>ServiceRegistration</code> object for the
      * service.
      * @return A service object that <strong>must </strong> be an instance of
      * all the classes named when the service was registered.
      * @see BundleContext#getService
      */
     public Object getService(Bundle bundle, ServiceRegistration registration);

     /**
      * Releases a service object.
      *
      * <p>
      * The Framework invokes this method when a service has been released by a
      * bundle. The service object may then be destroyed.
      *
      * @param bundle The bundle releasing the service.
      * @param registration The <code>ServiceRegistration</code> object for the
      * service.
      * @param service The service object returned by a previous call to the
      * <code>ServiceFactory.getService</code> method.
      * @see BundleContext#ungetService
      */
     public void ungetService(Bundle bundle, ServiceRegistration registration,
             Object service);
 }

